<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>String Stats Aggregation | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="search-aggregations-metrics.html" title="Metrics Aggregations">
<link rel="prev" href="search-aggregations-metrics-scripted-metric-aggregation.html" title="Scripted Metric Aggregation">
<link rel="next" href="search-aggregations-metrics-sum-aggregation.html" title="Sum Aggregation">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="search-aggregations.html">Aggregations</a></span>
»
<span class="breadcrumb-link"><a href="search-aggregations-metrics.html">Metrics Aggregations</a></span>
»
<span class="breadcrumb-node">String Stats Aggregation</span>
</div>
<div class="navheader">
<span class="prev">
<a href="search-aggregations-metrics-scripted-metric-aggregation.html">« Scripted Metric Aggregation</a>
</span>
<span class="next">
<a href="search-aggregations-metrics-sum-aggregation.html">Sum Aggregation »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="search-aggregations-metrics-string-stats-aggregation"></a>String Stats Aggregation<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/aggregations/metrics/string-stats-aggregation.asciidoc">edit</a><a class="xpack_tag" href="/subscriptions"></a>
</h2>
</div></div></div>
<p>A <code class="literal">multi-value</code> metrics aggregation that computes statistics over string values extracted from the aggregated documents.
These values can be retrieved either from specific <code class="literal">keyword</code> fields in the documents or can be generated by a provided script.</p>
<p>The string stats aggregation returns the following results:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">count</code> - The number of non-empty fields counted.
</li>
<li class="listitem">
<code class="literal">min_length</code> - The length of the shortest term.
</li>
<li class="listitem">
<code class="literal">max_length</code> - The length of the longest term.
</li>
<li class="listitem">
<code class="literal">avg_length</code> - The average length computed over all terms.
</li>
<li class="listitem">
<code class="literal">entropy</code> - The <a href="https://en.wikipedia.org/wiki/Entropy_(information_theory)" class="ulink" target="_top">Shannon Entropy</a> value computed over all terms collected by
the aggregation. Shannon entropy quantifies the amount of information contained in the field. It is a very useful metric for
measuring a wide range of properties of a data set, such as diversity, similarity, randomness etc.
</li>
</ul>
</div>
<p>Assuming the data consists of twitter messages:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /twitter/_search?size=0
{
    "aggs" : {
        "message_stats" : { "string_stats" : { "field" : "message.keyword" } }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/385.console"></div>
<p>The above aggregation computes the string statistics for the <code class="literal">message</code> field in all documents. The aggregation type
is <code class="literal">string_stats</code> and the <code class="literal">field</code> parameter defines the field of the documents the stats will be computed on.
The above will return the following:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
    ...

    "aggregations": {
        "message_stats" : {
            "count" : 5,
            "min_length" : 24,
            "max_length" : 30,
            "avg_length" : 28.8,
            "entropy" : 3.94617750050791
        }
    }
}</pre>
</div>
<p>The name of the aggregation (<code class="literal">message_stats</code> above) also serves as the key by which the aggregation result can be retrieved from
the returned response.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_character_distribution"></a>Character distribution<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/aggregations/metrics/string-stats-aggregation.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The computation of the Shannon Entropy value is based on the probability of each character appearing in all terms collected
by the aggregation. To view the probability distribution for all characters, we can add the <code class="literal">show_distribution</code> (default: <code class="literal">false</code>) parameter.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /twitter/_search?size=0
{
    "aggs" : {
        "message_stats" : {
            "string_stats" : {
                "field" : "message.keyword",
                "show_distribution": true  <a id="CO206-1"></a><i class="conum" data-value="1"></i>
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/386.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO206-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>Set the <code class="literal">show_distribution</code> parameter to <code class="literal">true</code>, so that probability distribution for all characters is returned in the results.</p>
</td>
</tr>
</table>
</div>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
    ...

    "aggregations": {
        "message_stats" : {
            "count" : 5,
            "min_length" : 24,
            "max_length" : 30,
            "avg_length" : 28.8,
            "entropy" : 3.94617750050791,
            "distribution" : {
                " " : 0.1527777777777778,
                "e" : 0.14583333333333334,
                "s" : 0.09722222222222222,
                "m" : 0.08333333333333333,
                "t" : 0.0763888888888889,
                "h" : 0.0625,
                "a" : 0.041666666666666664,
                "i" : 0.041666666666666664,
                "r" : 0.041666666666666664,
                "g" : 0.034722222222222224,
                "n" : 0.034722222222222224,
                "o" : 0.034722222222222224,
                "u" : 0.034722222222222224,
                "b" : 0.027777777777777776,
                "w" : 0.027777777777777776,
                "c" : 0.013888888888888888,
                "E" : 0.006944444444444444,
                "l" : 0.006944444444444444,
                "1" : 0.006944444444444444,
                "2" : 0.006944444444444444,
                "3" : 0.006944444444444444,
                "4" : 0.006944444444444444,
                "y" : 0.006944444444444444
            }
        }
    }
}</pre>
</div>
<p>The <code class="literal">distribution</code> object shows the probability of each character appearing in all terms. The characters are sorted by descending probability.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_script_12"></a>Script<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/aggregations/metrics/string-stats-aggregation.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Computing the message string stats based on a script:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /twitter/_search?size=0
{
    "aggs" : {
        "message_stats" : {
             "string_stats" : {
                 "script" : {
                     "lang": "painless",
                     "source": "doc['message.keyword'].value"
                 }
             }
         }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/387.console"></div>
<p>This will interpret the <code class="literal">script</code> parameter as an <code class="literal">inline</code> script with the <code class="literal">painless</code> script language and no script parameters.
To use a stored script use the following syntax:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /twitter/_search?size=0
{
    "aggs" : {
        "message_stats" : {
            "string_stats" : {
                "script" : {
                    "id": "my_script",
                    "params" : {
                        "field" : "message.keyword"
                    }
                }
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/388.console"></div>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_value_script_6"></a>Value Script<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/aggregations/metrics/string-stats-aggregation.asciidoc">edit</a>
</h4>
</div></div></div>
<p>We can use a value script to modify the message (eg we can add a prefix) and compute the new stats:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /twitter/_search?size=0
{
    "aggs" : {
        "message_stats" : {
            "string_stats" : {
                "field" : "message.keyword",
                "script" : {
                    "lang": "painless",
                    "source": "params.prefix + _value",
                    "params" : {
                        "prefix" : "Message: "
                    }
                }
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/389.console"></div>
</div>

</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_missing_value_11"></a>Missing value<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/aggregations/metrics/string-stats-aggregation.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The <code class="literal">missing</code> parameter defines how documents that are missing a value should be treated.
By default they will be ignored but it is also possible to treat them as if they had a value.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /twitter/_search?size=0
{
    "aggs" : {
        "message_stats" : {
            "string_stats" : {
                "field" : "message.keyword",
                "missing": "[empty message]" <a id="CO207-1"></a><i class="conum" data-value="1"></i>
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/390.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO207-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>Documents without a value in the <code class="literal">message</code> field will be treated as documents that have the value <code class="literal">[empty message]</code>.</p>
</td>
</tr>
</table>
</div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="search-aggregations-metrics-scripted-metric-aggregation.html">« Scripted Metric Aggregation</a>
</span>
<span class="next">
<a href="search-aggregations-metrics-sum-aggregation.html">Sum Aggregation »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
